MIDP: Bluetooth OBEX Example - Business Card Exchanger 
-------------------------

This MIDP application demonstrates the usage of the JSR-82 Bluetooth OBEX API by exchanging 
business cards between devices. The OBEX API is currently supported by the S60 
platform, from S60 2nd Edition, Feature Pack 3 onwards.

--------------------------------------------------------------------------------

PREREQUISITES

MIDP 2.0 basics and knowledge of the JSR-82 mandatory part (javax.bluetooth).
In addition, knowledge of the PIM API (JSR-175) can be helpful in understanding 
the example.

--------------------------------------------------------------------------------

IMPORTANT FILES/CLASSES

resources:
res\icon.png

classes:
src\bcexchanger\AddressBook.java
src\bcexchanger\BCExchangerMIDlet.java
src\bcexchanger\Storage.java

src\bcexchanger\comm\ExchangerListener.java
src\bcexchanger\comm\ExchangerComm.java
src\bcexchanger\comm\ExchangerCommImpl.java
src\bcexchanger\comm\ExchangerState.java
src\bcexchanger\comm\ExcahngerStateParant.java
src\bcexchanger\comm\IdleState.java
src\bcexchanger\comm\InquiryState.java
src\bcexchanger\comm\ReceiveState.java
src\bcexchanger\comm\SendState.java
src\bcexchanger\comm\ServiceDiscoveryState.java

src\bcexchanger\ui\AddressBookScreen.java
src\bcexchanger\ui\AlertMessage.java
src\bcexchanger\ui\MainScreen.java
src\bcexchanger\ui\ProgressScreen.java
src\bcexchanger\ui\Screen.java
src\bcexchanger\ui\ServiceListScreen.java

ANT build script:
build.xml
build.properties

--------------------------------------------------------------------------------

KNOWN ISSUES:

- On some devices (such as the Nokia N90) you need to change the suite settings to allow 
the application to use PIM data. Otherwise, you will receive an "Error during 
receiving" message when exchanging business cards. You can change the "Edit user
data" value to "Ask every time" from 
Tools | Manager | MIDlet suite (BCExchanger) | Options | Suite settings.

- Sometimes discovery is not complete when running the example on the emulator.

- There may be too few PIM entries for some tests. You may want to edit
them directly in the emulator.

- Although business cards are successfully transferred from emulator to emulator
using the Prototype SDK 3.0/4.0 and Nokia Connectivity Framework 1.2, the cards are not added to the contact lists.
    
--------------------------------------------------------------------------------

RUNNING THE EXAMPLE

There are four main views in the application:

"Main Screen" - From this screen the user can initiate an exchange of business 
            cards, change his or her own business card, and exit the application.

"Address Book" - This view shows the list of contacts of the address book. The user 
            can either choose a contact or exit the application.

"Progress Screen" - This view indicates that an operation is in progress. 
            For example when inquiry, service discovery, or business card sending 
            and receiving is running, this screen is displayed. With this 
            screen the user can cancel the process.

"Service List" - This view is used when several services are 
            available in the vicinity. It allows the user to choose the desired one. With this 
            screen the user can select the service or cancel the process.

Here are some quick instructions about how to run the example from the command line
and from Eclipse IDE:

1) Running the MIDlet from the command line: 
-------------------------------------
The MIDlet can be run in the Prototype SDK 4.0 from the command line:

[Prototype SDK install path]\bin\emulator.exe -Xdescriptor:[workspace path]\BCExchanger\BCExchanger.jad

2) Running the MIDlet from Eclipse IDE:
--------------------------------------
- Import BCExchanger project into your Eclipse workspace.
- Open BCExchanger project in the Package Explorer.
- Create a run configuration:
	1. Right click MediaSampler.jad
	2. Select "Run As | Run..."
	3. Select Nokia SDK Plug-in from the Configurations and press the "New" button.
	4. Select the SDK (eg. Prototype_4_0_S60_MIDP_Emulator)
	5. Press the "Run" button. 

During the next runs you can reuse the existing run configuration. For more detailed
instructions, please take a look at the SDK's User's Guide.
     
--------------------------------------------------------------------------------

BUILD & INSTALLATION INSTRUCTIONS

Configuring Eclipse and Carbide.j 1.0
-------------------------------------
The preferred method is to use Eclipse with Carbide.j 1.0 installed
as a plugin. Choose "File | Import | Existing Project into Workspace" in
the top menu of Eclipse and browse to the MediaSampler folder. This will add
the project to your Workspace.

You may need to properly configure the Built Path in "Project | Properties |
Java Build Path | Libraries" to point to the right location of the Nokia 
Prototype SDK 4.0. In addition, ensure that Carbide.j 1.0 is configured
to use the Prototype SDK 4.0 from "Emulators | Configure Emulator..." menu.


Compiling using Ant
-------------------
A build.xml file that uses the ANT tasks of Carbide.j 1.0 is included. It may be necessary to modify the location of 
Carbide.j and the desired emulator/device from the build.xml file.

Check Carbide.j's documentation for more information
about Carbide.j's ANT tasks.
    
--------------------------------------------------------------------------------

COMPATIBILITY

S60 3rd Edition
S60 2nd Edition, Feature Pack 3

The example application has been tested on the Nokia N70, the Nokia N71, the Nokia N80, and the Nokia N90 devices.
In addition, it has been tested on a development SDK (Nokia Prototype SDK 4.0 for Java Platform, Micro Edition, S60 device).
    
--------------------------------------------------------------------------------

ADDITIONAL DOCUMENTATION

See the document MIDP: OBEX API Developer's Guide for further
information.

--------------------------------------------------------------------------------
EVALUATE THIS RESOURCE   
Please spare a moment to help us improve documentation quality and recognize the examples you find most valuable, 
by rating this resource at 
http://www.forum.nokia.com/main/1%2C%2C90%2C00.html?surveyId=b37cb6fa-fa2b-429c-9d1e-3b9728a23ac8/MIDP_Bluetooth_OBEX_Example_Business_Card_Exchange_v1_0_en.zip.



